home *** CD-ROM | disk | FTP | other *** search
/ HyperLib 1997 Winter - Disc 1 / HYPERLIB-1997-Winter-CD1.ISO.7z / HYPERLIB-1997-Winter-CD1.ISO / オンラインウェア / UTIL / Tim's Widgets 1.3.sit / Tim's Widgets 1.3 / Tim's Widgets Docu_ReadMe < prev    next >
Text File  |  1996-02-09  |  15KB  |  200 lines
  1. Timﾕs Widgets 1.3
  2. ｩ 1994-1996, Two Bits Worth, Inc.
  3.  
  4. Shareware:  $20.00
  5.  
  6. And now a word from the lawyersﾉ
  7. This software is a copyrighted work, it is not and never has been in the public domain.  You may use this software to evaluate its usefulness if your evaluation is strictly for private and non-commercial use.  You may give a copy of this software to another individual if you include the software's README file and all other related software materials.  This software may not be sold, incorporated into other products, or in anyway commercially exploited without prior written consent of the author.  If you want to continue using this software beyond your evaluation, please send $20.00 to the address listed below.
  8.  
  9. TWO BITS WORTH MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE PACKAGE DESCRIBED BELOW, ITS MERCHANTABILITY, OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.  YOU ASSUME THE ENTIRE RISK OF USING THE SOFTWARE, INCLUDING ANY LOSS OR DAMAGE OF DATA OR MATERIALS RESULTING FROM ITS USE.  THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.  THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.  THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS.  THERE MAY BE OTHER RIGHTS YOU HAVE WHICH VARY FROM STATE TO STATE.
  10.  
  11. Written by Tim Herzog
  12. Produced by Two Bits Worth
  13. 778 Hague Avenue
  14. Saint Paul, MN  55104
  15. (612) 227-2920
  16. Internet:  herzo005@gold.tc.umn.edu
  17. Make checks payable to Two Bits Worth
  18.  
  19. Background
  20.  
  21. Timﾕs Widgets is a collection of utility functions which (I think) are very useful, especially for hackers and programmer types.  Each by itself does not warrant a full-blown program, so I put all these tidbits into one program.  As I discover (or have suggested to me) other knick-knacky types of functions, Iﾕll probably add them to TWﾕs feature set.
  22.  
  23. TW runs native on the PowerMac.
  24.  
  25.  
  26. Text Translator:
  27.  
  28. This is a text processing feature that covers a lot of ground.  Basically, it reads in a text file or set of text files, performs processing, and writes out the results.  When you choose Text Translator from the menu, you get the File Open dialog box.  You can choose an entire folder by clicking the button with the name of the current folder, or you can choose just one file by selecting the file.  TW displays the current Text Translator options in Geneva 9-point.  You can change the current translator preferences by clicking the Preferences button (this is the same as choosing Text Translator from the Preferences popup menu in the File menu).
  29.  
  30.  
  31. Text Translator Preferences:
  32.  
  33. Output Format:  Macintosh, Dos/Windows.  Choose the output format for the processed files.
  34.  
  35. Remove ｦ Returns:  If checked, TW will replace single paragraph returns with a space and double paragraph returns with a single paragraph return.  This is useful for people who pull files off the Internet where the authorﾕs system ﾔconvenientlyﾕ put in a hard return at the end of every line, which makes reformatting a real hassle.  BE CAREFUL!  This option can REALLY mess up files for which it makes no sense, such as source code files and files that have already been run once with this option.  Youﾕll end up with one BIG LONG line!
  36.  
  37. Process Subfolders:  If checked and you chose a folder, TW will also process files in subfolders.  By the way, this option is the same as the one in Line Count Preferences, so if you check it once here, it will be checked in Line Count Preferences as well.
  38.  
  39. Retain File Dates:  Donﾕt change the date on the processed files.
  40.  
  41. Copy to New Files:  If checked, TW will copy results of each file to a new file.  The new file will have the same name as the old file with ﾒ copyﾓ appended on the end.  If such a file already exists, TW will warn you and ask you if you want to overwrite it.  If this option is not checked, TW will write results to the original file, OVERWRITING the original contents.  BE CAREFUL with this option!
  42.  
  43. Process All Files:  Process all files, whether or not the Macintosh system recognizes them as text files (TW never tries to process applications).  This is handy for files that youﾕve ported from DOS where the system may not recognize them as text.  This option is the same as the one in Line Count Preferences, so if you check it once here, it will be checked in Line Count Preferences as well.
  44.  
  45. Skip Warnings:  If checked, TW will not warn you before embarking on destructive behavior; that is, writing results to files that already exist.  Note that this option is automatically ON if you are running TW via AppleScript.
  46.  
  47.  
  48. Line Counter:  This feature counts lines of text in a file or set of files and displays the results in a window.  When you choose Line Counter from the menu, you get the File Open dialog box (similar to the one for Text Translator).  You can choose an entire folder by clicking the button with the name of the current folder, or you can choose just one file by selecting the file.  TW displays the current Line Counter options in Geneva 9-point.  You can change the current line count preferences by clicking the Preferences button (this is the same as choosing Line Counter from the Preferences popup menu in the File menu).
  49.  
  50.  
  51. Line Counter Preferences:
  52.  
  53. Perform Count On:  All Text Files, .c Files Only, .h Files Only, .c And .h Files Only:  This option sets which files will be counted when choosing a folder or set of folders. 
  54.  
  55. Process Subfolders:  same as the identical option in Text Translator Preferences (see above).
  56.  
  57. Process All Files:  same as the identical option in Text Translator Preferences (see above).
  58.  
  59.  
  60. Resource to PICT File:  This feature lets you select a file with a PICT resource in it, previews the file so you can select a PICT resource, and then copies the selected PICT resource to a PICT file, which can be edited by any graphic program that supports PICT.
  61.  
  62.  
  63. PICT File to Resource:  This feature lets you select a PICT file and then copies it as a PICT resource to a designated resource file.  You can pick whether the resource file is a new file or an existing file.
  64.  
  65.  
  66. Preferences:  Lets you set preferences for Text Translator, Line Counter, and Mixed Mode Code (see the corresponding features for details).
  67.  
  68.  
  69. Suitcase ID <-> Varityper ID:  This feature is extremely obscure, but here it is.  Suitcase is a utility by Symantec (formerly by Fifth Dimension) that lets you manage fonts.  Varityper makes a set of utilities that give you a lot of information about the fonts in your system.  At least, I think they still do, Iﾕm not sure.  Anyway, both programs let you generate files listing font ID numbers and font names for the purposes of diagnosing and correcting font conflicts between different systems.  This feature lets you convert font ID files from one format to the other.  There, I told you it was obscure.
  70.  
  71. Anyway, when you select this feature from the menu, TW asks you to select a font ID file.  Choose a file in either format, and TW converts it to the other format.
  72.  
  73.  
  74. Mixed Mode Code:  If you're not a programmer, forget this feature.  If you are a programmer, but have never had to deal with callback routines in a mixed code environment (e.g., 680x0 and native power mac), forget this feature.  This feature is here because I was dealing literally with hundreds of callback routines in a mixed code environment.  I may be the only person in the world to use this function, but if there's another poor soul out there who got stuck writing a bunch of mixed mode macros (for example, for function callbacks in code resources), this could save you dozens of hours of coding and tedious debugging.
  75.  
  76. This feature lets you enter function prototypes (in C), then it parses those prototypes and generates typedef declarations and macros to implement those prototypes in a mixed mode environment.  This is the equivalent of the NewRoutineDescriptor() macros that you find scattered throughout Apple's universal headers.  Again, if this isn't yet ringing any bells, forget this feature.
  77.  
  78. Type (or paste) your function prototypes into the text box (with a carriage return between each) and click Convert.  TW generates the mixed mode code and places it in the text box.  If the amount of code exceeds the capacity of the text box, it places partial code in the text box and pastes the complete code onto the clipboard.  Alternatively, you can click "Convert To/From Clipboard," and TW will use the clipboard contents as input, and will replace its contents with the processed output.  Click Preference to set preferences for mixed mode code generation.
  79.  
  80. The parsing algorithm is not very sophisticated!  Keep your prototypes simple, and use typedefs to simplify more complex declarations, like function pointers.  Also, although TW has an option to include argument names, it is a very simplistic option, and TW has a good chance of goofing it up if your arguments have any degree of complexity.  Try to avoid argument names in your function prototypes.  For example,
  81.  
  82. int Foo(double *, ProcPtr);
  83.  
  84. is preferrable to:
  85.  
  86. int Foo(double *myDouble, ProcPtr myProcPtr);
  87.  
  88. TW won't be able to handle this one:
  89.  
  90. short Foo(long, void (*)(short, short));
  91.  
  92. Instead, typedef the procedure pointer:
  93.  
  94. typedef void (*FooCallbackProcPtr)(short, short);
  95.  
  96. and declare the function like this:
  97.  
  98. short Foo(long, FooCallbackProcPtr);
  99.  
  100.  
  101. Mixed Mode Code Preferences:
  102.  
  103. C Functions are kThinkCStackBased:  If selected, C functions are assumed to follow the kThinkCStackBased calling conventions, instead of the kCStackBased conventions.  Select this option if you are using the Symantec or THINK compilers.
  104.  
  105. Tab Spacing:  sets how many spaces are used per tab character in your text editor.
  106.  
  107. Minimum Tabs in #defines:  controls spacing in #define statements.  If your function names are rather long, increase this number if you want your #defines to line up all neat and pretty with each other.  I recommend a setting of 8-10.
  108.  
  109. Pascal Keyword:  TW determines if a function is kPascalStackBased or not by looking for the "pascal" keyword.  If you use another keyword to indicate pascal calling conventions, enter that keyword here.  For example, to convert the following, you would need to enter APFUNCTYPE:
  110.  
  111. #define APFUNCTYPE pascal    // Declared in one of your headers
  112.  
  113. // prototype to be converted
  114. APFUNCTYPE void Foo(short);
  115.  
  116. Variable Names in Argument List:  If selected, TW will scan for names in the function's argument list.  However, it is still suggested that you omit them, as the parsing routine is not very savvy.  See caveats above.
  117.  
  118. For explanations of the following checkboxes, assume that you entered the function prototype:
  119.  
  120. long SampleProc(short, long, void *);
  121.  
  122. "upp{proc}ProcInfo #defines" generates this code:
  123.  
  124. #define uppSampleProcProcInfo    (ProcInfoType) kCStackBased | ¥
  125.     RESULT_SIZE(SIZE_CODE(sizeof(long))) | ¥
  126.     STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short))) | ¥
  127.     STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(long))) | ¥
  128.     STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void *)))
  129.  
  130.  
  131. "{proc}Upp typedefs" generates this code:
  132.  
  133. typedef long (*SampleProcProcPtr)(short, long, void *);
  134.  
  135. #if USESROUTINEDESCRIPTORS
  136.     typedef UniversalProcPtr SampleProcUPP;
  137. #else
  138.     typedef SampleProcProcPtr SampleProcUPP;
  139. #endif
  140.  
  141.  
  142. "Call{proc}Proc macros" generates this code:
  143.  
  144. #if USESROUTINEDESCRIPTORS
  145.     #define CallSampleProcProc(userRoutine, a, b, c) ¥
  146.             (long) CallUniversalProc((UniversalProcPtr) userRoutine, uppSampleProcProcInfo,  (short) a, (long) b, (void *) c)
  147. #else
  148.     #define CallSampleProcProc(userRoutine, a, b, c) ¥
  149.             (*(userRoutine))(a, b, c)
  150. #endif
  151.  
  152.  
  153. "New Proc{proc}Proc macros" generates this code:
  154.  
  155. #if USESROUTINEDESCRIPTORS
  156. #define NewSampleProcProc(userRoutine) ¥
  157.         NewRoutineDescriptor((ProcPtr) userRoutine, uppSampleProcProcInfo, GetCurrentISA())
  158. #else
  159. #define NewSampleProcProc(userRoutine)                (userRoutine)
  160. #endif
  161.  
  162. "New {proc}Proc code" is a little different.  This is handy if you have an array or struct of function pointers, to which you are assigning the results of the mixed mode macros.  You can automatically generate assignment code like this:
  163.  
  164. funcArray[0] = (SampleProcUPP) NewSampleProcProc(SampleProc);
  165.  
  166. In the "Variable Name" text box, enter the variable to which the mixed mode macro results should be assigned.  Now obviously, if you're generating more than one prototype, you'll need some flexibility.  So use the following conventions:
  167.  
  168. Number signs (#) are replaced with a zero-based enumerator.  For example, use funcArray[#] to assign each function to an element in an array.
  169.  
  170. Asterisks (*) are replaced with the original function name.  If a number follows the asterisk (*3), then that many characters are removed from the end of the function name.  If a carat (^) precedes the number, the characters are removed from the beginning of the function name.  Also, when the asterisk is used, TW casts to a ProcPtr, not a UPP.
  171.  
  172. For example:
  173.  
  174. functionBlock.*4Ptr
  175.  
  176. becomes:
  177.  
  178. functionBlock.SamplePtr = (SampleProcProcPtr) NewSampleProcProc(SampleProc);
  179.  
  180.  
  181.  
  182. AppleEvent Support:  TW fully supports AppleEvents, including dragging and dropping of objects on the TW program icon.  Any text file can be dropped onto TWﾕs icon and TW will perform a Line Count on that file (as if you had selected the file with the Line Count item in the File menu).  You can also drag and drop the iconﾕs of folders or disks.
  183.  
  184. Running TW with AppleScript:  Both Text Translator and Line Count can be run via AppleScript.  The syntax for running TW via AppleScript is as follows:
  185.  
  186. texttrans  file [output mac|dos] [subfolders bool] [savedate bool] [savecopy bool] [shortparas bool] [allfiles bool]
  187.  
  188. This command conducts a Text Translator session.  ﾒfileﾓ can be either a file name or a path to a folder.  The rest of the parameters are optional and correspond to the options in the Text Translator Preferences dialog box.  If any parameter is missing, TW uses the original setting from the Text Translator Preferences dialog box.
  189.  
  190. NOTE:  Text Translator runs with ﾒSkip Warningsﾓ ON when driven via AppleScript (since thereﾕs a good change that TW will be running in the background).
  191.  
  192. linecount  file [files all|c|h|ch] [subfolders bool] [allfiles bool]
  193.  
  194. This command conducts a Line Count session.  ﾒfileﾓ can be either a file name or a path to a folder.  The rest of the parameters are optional and correspond to the options in the Line Count Preferences dialog box.  If any parameter is missing, TW uses the original setting from the Line Count Preferences dialog box.
  195.  
  196. clear linecount
  197.  
  198. This command clears the contents of the Line Count display window.
  199.  
  200. TW comes with two sample AppleScripts for running itself in conjunction with THINK C or Symantec C to count the lines of code in a project.  Place ﾒCount Lines (TPM)ﾓ in your ﾒ(AppleScripts)ﾓ folder to make the AppleScript appear in the AppleScript menu under THINK C.  For Symantec C, place ﾒCount Lines (SPM)ﾓ in your ﾒ(Scripts Menu)ﾓ folder.  The Symantec C version has the additional feature of counting lines in header files.